docs: "user guide" section cleanup #826

zilto · 2024-04-16T20:04:03Z

Changes

Renamed the section from "How To Guides" to "User Guide".
Changed the title of "User Guide" pages to be easier to visually scan. Essentially, this consists of shorter titles with the most important word at the beginning
changed the order of user guide items
updated the list of integrations

Before:

After:

How I tested this

build docs locally

Notes

Checklist

PR has an informative and human-readable title (this will be pulled into the release notes)
Changes are limited to a single goal (no scope creep)
Code passed the pre-commit check & code is left cleaner/nicer than when first encountered.
Any change in functionality is tested
New functions are documented (with a description, list of inputs, and expected output)
Placeholder code is flagged / future TODOs are captured in comments
Project documentation has been updated if adding/changing functionality.

Renamed the section from "How To Guides" to "User Guide". Changed the title of "User Guide" pages to be easier to visually scan. Essentially, this consists of shorter titles with the most important word at the beginning

docs/how-tos/custom-driver.rst

docs/how-tos/async.rst

docs/how-tos/load-data.rst

docs/how-tos/use-without-pandas.rst

skrawcz · 2024-04-16T22:34:22Z

To me the purpose of the how-to section is for goal oriented people - "I want to do X with Hamilton" where X is a broad concept -- while the integrations section is when X is a specific narrower technology/topic.

So I think the changes mostly look good. Left comments where appropriate.

zilto · 2024-04-17T14:22:20Z

To me the purpose of the how-to section is for goal oriented people - "I want to do X with Hamilton" where X is a broad concept -- while the integrations section is when X is a specific narrower technology/topic.

I agree on the purpose of the "how-to" / "user guide" section. I believe "User guide" pages should mirror frequent Q/A on Slack. Pages on "Feature engineering", "pre-commit", "jupyter notebooks" are good examples.

Many of the current pages are too introductory / generic. In that case, it should be reframed to be part of the "Concepts" section (e.g., "Load data" doesn't add much compared to the materialization page).

docs: "user guide" section cleanup

326d800

Renamed the section from "How To Guides" to "User Guide". Changed the title of "User Guide" pages to be easier to visually scan. Essentially, this consists of shorter titles with the most important word at the beginning

zilto added the documentation Improvements or additions to documentation label Apr 16, 2024